<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <title>bdep-ci(1) bdep 0.17.0</title>

  <style type="text/css">
/* file      : common.css
 * license   : MIT; see accompanying LICENSE file
 */

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard paragraph. */

p, pre {margin: 1em 0 1em 0;}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}
@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

/* file      : pre-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css. */

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* file      : man.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Bases:
 *
 * common.css
 * pre-box.css
 *
 */

#content
{
  max-width: 42.1em;
  padding-left: 1.5em; /* Reserve for the heading. */
}

h1
{
  font-weight: normal;
  font-size: 1.58em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.88em;
}

/* Definition list for options. */
dl.options dt {margin: 1em 0 0 0;}
dl.options dd {margin: .1em 0 0 4.5em;}

/* Make lists inside option descriptions a tad smaller. */
dl.options dd ul, dl.options dd ol, dl.options dd dl
{
  font-size: 0.889em;
  line-height: 1.4em;
}

  </style>

</head>
<body>
<div id="content">

  <h1>NAME</h1>

  <p><b><code>bdep-ci</code></b> &#8211; submit project test request to CI server</p>
  <h1>SYNOPSIS</h1>

  <p class="code"><code><b>bdep ci</b> [<i>options</i>] [<i>cfg-spec</i>]
  [<i>pkg-spec</i>]</code></p>

  <p class="code"><code><i>cfg-spec</i> = (<b>@</b><i>cfg-name</i> |
  <b>--config</b>|<b>-c</b> <i>cfg-dir</i>)... | <b>--all</b>|<b>-a</b> |
  <b>--forward</b>
  <br/>
  <i>pkg-spec</i> = (<b>--directory</b>|<b>-d</b> <i>pkg-dir</i>)... |
  <i>prj-spec</i>
  <br/>
  <i>prj-spec</i> = <b>--directory</b>|<b>-d</b> <i>prj-dir</i></code></p>

  <h1>DESCRIPTION</h1>

  <p>The <code><b>ci</b></code> command submits the project packages test
  request to a CI server.</p>

  <p>If no project or package directory is specified, then the current working
  directory is assumed. If no configuration is specified, then the default
  configurations are used. If the specified directory is a project directory,
  then all the packages initialized in the configurations are submitted,
  unless the <code><b>--forward</b></code> option is specified (see below).
  See <a
  href="bdep-projects-configs.xhtml"><code><b>bdep-projects-configs(1)</b></code></a>
  for details on specifying projects and configurations.</p>

  <p>A CI request consists of the specified packages and their versions as
  well as the project's remote version control repository URL corresponding to
  the current (local) state of the project. The CI server should be able to
  fetch these package versions from this repository as well as any
  dependencies from this repository or its prerequisite/complement
  repositories, according to each package's
  <code><b>repositories.manifest</b></code>.</p>

  <p>If the CI server is not explicitly specified with the
  <code><b>--server</b></code> option, the request is submitted to
  <code><b>ci.cppget.org</b></code> by default.</p>

  <p>Unless the remote repository URL is specified with the
  <code><b>--repository</b></code> option, it will be automatically derived
  from the version control's "remote" URL. In case of
  <code><b>git(1)</b></code>, it will be based on the
  <code><b>remote.origin.url</b></code> configuration value unless overridden
  with <code><b>remote.origin.build2Url</b></code>. The repository URL is then
  adjusted to corresponding to the current (local) state of the project. In
  case of <code><b>git(1)</b></code>, the current branch and commit id are
  added as the repository URL fragment (see <a
  href="../../bpkg/doc/bpkg-repository-types.xhtml"><code><b>bpkg-repository-types(1)</b></code></a>
  for details).</p>

  <p>Some package manifest values can be overridden as part of the CI request
  submission using the <code><b>--override</b></code> and
  <code><b>--overrides-file</b></code> options as well as their
  <code><b>--builds</b></code>, <code><b>--build-config</b></code>,
  <code><b>--target-config</b></code>, <code><b>--package-config</b></code>,
  and <code><b>--build-email</b></code> shortcuts. This is primarily useful
  for specifying alternative build configurations and/or build notification
  emails. For example:</p>

  <pre>$ bdep ci --builds gcc
$ bdep ci --builds network/gcc
$ bdep ci --target-config 'linux*-gcc*'
$ bdep ci --package-config network
$ bdep ci --build-config 'network/linux*-gcc*'

$ bdep ci --override \
  'default-build-config: config.foo.cache=true config.foo.buffer=16'

$ bdep ci --override 'mytest-build-config: config.foo.cache=true' \
  --package-config mytest

$ bdep ci --override 'build-auxiliary: *-postgresql_16'</pre>

  <p>Manifest overrides other than
  <code>[<b>*-</b>]<b>build-auxiliary</b>[<b>-*</b>]</code> override the
  entire value group that they belong to. The
  <code>[<b>*-</b>]<b>build-auxiliary</b>[<b>-*</b>]</code> values only
  override the matching values, which are expected to already be present in
  the package manifest. Currently, the following value groups/values can be
  overridden. The <code><b>build-*email</b></code> group is overridden by
  default as if by specifying an empty build email.</p>

  <pre>build-email build-{warning,error}-email
builds build-{include,exclude}
build-bot
*-builds *-build-{include,exclude}
*-build-bot
*-build-config
*-build-email *-build-{warning,error}-email

[*-]build-auxiliary[-*]</pre>

  <p>For the package configuration-specific build constraint, email,
  auxiliary, and custom bot public key overrides, the corresponding
  configuration must exist in the package manifest. In contrast, the package
  configuration override (<code><b>*-build-config</b></code>) adds a new
  configuration if it doesn't exist and updates the arguments of the existing
  configuration otherwise. In the former case, all the potential build
  constraint, email, auxiliary, and custom bot public key overrides for such a
  newly added configuration must follow the corresponding
  <code><b>*-build-config</b></code> override.</p>

  <p>Note that the build constraints group values (both common and build
  package configuration-specific) are overridden hierarchically so that the
  <code>[<b>*-</b>]<b>build-</b>{<b>include</b>,<b>exclude</b>}</code>
  overrides don't affect the respective <code>[<b>*-</b>]<b>builds</b></code>
  values.</p>

  <p>Note also that the common and build package configuration-specific build
  constraints group value overrides are mutually exclusive. If the common
  build constraints are overridden, then all the configuration-specific
  constraints are removed. Otherwise, if any configuration-specific
  constraints are overridden, then for the remaining configurations the build
  constraints are reset to <code><b>builds:&#160;none</b></code>.</p>

  <p>Similar to the build constraints groups, the common and build package
  configuration-specific custom bot public key value overrides are mutually
  exclusive. If the common build custom bot public keys are overridden, then
  all the configuration-specific custom bot public keys are removed.
  Otherwise, if any configuration-specific custom bot public keys are
  overridden, then for the remaining configurations the custom bot public keys
  are left unchanged.</p>

  <p>Similar to the above, the common and build package configuration-specific
  build emails group value overrides are mutually exclusive. If the common
  build emails are overridden, then all the configuration-specific emails are
  removed. Otherwise, if any configuration-specific emails are overridden,
  then for the remaining configurations the build emails are reset to the
  empty values and the build warning and error emails are removed (which
  effectively disables email notifications for such configurations).</p>

  <p>If supported by the CI service, a package can be tested interactively in
  a specific build configuration using the
  <code><b>--interactive</b>|<b>-i</b></code> option. In this mode the CI
  service provides the login information for the execution environment and
  pauses the testing at the specified breakpoint.</p>

  <p>While the exact interpretation of the CI request depends on the specific
  service, normally, the CI server will respond with a reference that can be
  used to query the results. See <a
  href="../../brep/doc/build2-repository-interface-manual.xhtml#ci">Package
  CI</a> for details on the CI request handling.</p>

  <p>If the <code><b>--forward</b></code> option is specified then the
  forwarded configurations are used instead of the default configurations. In
  particular, this means that in this mode the project doesn't need to be
  initialized and all that's required is for package's source directories to
  be configured to forward to an out of source build configuration (see <a
  href="../../build2/doc/b.xhtml"><code><b>b(1)</b></code></a> for details on
  forwarded configurations). This, for example, can be used to submit packages
  that don't use the standard version.</p>

  <h1>CI OPTIONS</h1>

  <dl class="options">
    <dt><code><b>--yes</b></code>|<code><b>-y</b></code></dt>
    <dd>Don't prompt for confirmation before submitting.</dd>

    <dt><code><b>--interactive</b></code>|<code><b>-i</b></code> <code><i>cf</i></code>[:<code><i>bp</i></code>]</dt>
    <dd>Test the package interactively in the specified build configuration,
    pausing the execution at the specified breakpoint. The build configuration
    is a target configuration (<code><i>tc</i></code>), optionally for a
    specific package configuration (<code><i>pc</i></code>) and/or for a
    specific target (<code><i>tg</i></code>):

    <p class="code"><code><i>cf</i> = [<i>pc</i><b>/</b>]<i>tc</i> |
    <i>pc</i><b>/</b><i>tc</i><b>/</b><i>tg</i></code></p>

    <p>Refer to the <code><b>--build-config</b></code> option for details on
    the build configuration component semantics. Note that for interactive
    testing they should identify a single build configuration. Failed that,
    the test request will be aborted.</p>

    <p>Valid breakpoint values are <code><b>none</b></code> (don't stop),
    <code><b>error</b></code> (stop after first error),
    <code><b>warning</b></code> (stop after first warning), as well as the CI
    service-specific step ids in which case the execution stops before
    performing the specified step (see <a
    href="../../bbot/doc/build2-build-bot-manual.xhtml#arch-worker"><code><b>bbot</b></code>
    worker step ids</a>). If no breakpoint is specified, then
    <code><b>error</b></code> is assumed.</p></dd>

    <dt><code><b>--server</b></code> <code><i>url</i></code></dt>
    <dd>CI server to submit the request to.</dd>

    <dt><code><b>--repository</b></code> <code><i>url</i></code></dt>
    <dd>Remote repository URL for the project.</dd>

    <dt><code><b>--override</b></code> <code><i>name</i></code>:<code><i>value</i></code></dt>
    <dd>Package manifest value override. Repeat this option to override
    multiple values.</dd>

    <dt><code><b>--overrides-file</b></code> <code><i>file</i></code></dt>
    <dd>Read manifest value overrides from the specified manifest fragment
    file. Repeat this option to specify multiple override files.</dd>

    <dt><code><b>--builds</b></code> [<code><i>pc</i></code>/]<code><i>class-expr</i></code></dt>
    <dd>Shortcut for the following option:

    <p
    class="code"><code><b>--override&#160;</b>[<i>pc</i><b>-</b>]<b>builds:</b><i>class-expr</i></code></p>

    <p>Repeat this option to specify multiple build target configuration
    classes.</p></dd>

    <dt><code><b>--build-config</b></code> <code><i>pc</i></code>/<code><i>tc</i></code>[/<code><i>tg</i></code>]</dt>
    <dd>Shortcut for the following options sequence:

    <p>[<code><b>--override&#160;</b><code><i>pc</i></code><b>-builds:all</b></code>]
    <br/>
    <code><b>--override&#160;</b><code><i>pc</i></code><b>-build-include:</b><code><i>tc</i></code>[<b>/</b><code><i>tg</i></code>]</code>
    <br/>
    <code><b>--override&#160;</b><code><i>pc</i></code><b>-build-exclude:**</b></code></p>

    <p>The first override is omitted from the above sequence if the
    <code><code><i>pc</i></code><b>-builds</b></code> override is specified on
    the command line.</p>

    <p>Repeat this option to specify multiple build configurations.</p></dd>

    <dt><code><b>--target-config</b></code> <code><i>tc</i></code>[/<code><i>tg</i></code>]</dt>
    <dd>Shortcut for the following options sequence:

    <p>[<code><b>--override&#160;builds:all</b></code>]
    <br/>
    <code><b>--override&#160;build-include:</b><code><i>tc</i></code>[<b>/</b><code><i>tg</i></code>]</code>
    <br/>
    <code><b>--override&#160;build-exclude:**</b></code></p>

    <p>The first override is omitted from the above sequence if the
    <code><b>builds</b></code> override is specified on the command line.</p>

    <p>Repeat this option to specify multiple build target
    configurations.</p></dd>

    <dt><code><b>--package-config</b></code> <code><i>pc</i></code></dt>
    <dd>Shortcut for the following options sequence:

    <p><code><b>--override&#160;</b><code><i>pc</i></code><b>-builds:</b>...</code>
    <br/>
    <code><b>--override&#160;</b><code><i>pc</i></code><b>-build-include:</b>...</code>
    <br/>
    <code><b>--override&#160;</b><code><i>pc</i></code><b>-build-exclude:</b>...</code></p>

    <p>Where the override values are the build constraints for the specified
    build package configuration from the package manifest.</p>

    <p>Repeat this option to specify multiple build package
    configurations.</p></dd>

    <dt><code><b>--build-email</b></code> <code><i>email</i></code></dt>
    <dd>Shortcut for the following option:

    <p
    class="code"><code><b>--override&#160;build-email:</b><i>email</i></code></p></dd>

    <dt><code><b>--simulate</b></code> <code><i>outcome</i></code></dt>
    <dd>Simulate the specified outcome of the CI process without actually
    performing any externally visible actions (such as testing the packages or
    publishing the result). The commonly used outcome value is
    <code><b>success</b></code>. For other recognized outcomes refer to the CI
    service documentation.</dd>

    <dt><code><b>--forward</b></code></dt>
    <dd>Use the forwarded configuration for each package instead of the
    default configuration.</dd>

    <dt><code><b>--all</b></code>|<code><b>-a</b></code></dt>
    <dd>Use all build configurations.</dd>

    <dt><code><b>--config</b></code>|<code><b>-c</b></code> <code><i>dir</i></code></dt>
    <dd>Specify the build configuration as a directory.</dd>

    <dt><code><b>--directory</b></code>|<code><b>-d</b></code> <code><i>dir</i></code></dt>
    <dd>Assume project/package is in the specified directory rather than in
    the current working directory.</dd>

    <dt><code><b>--config-name</b></code>|<code><b>-n</b></code> <code><i>name</i></code></dt>
    <dd>Specify the build configuration as a name.</dd>

    <dt><code><b>--config-id</b></code> <code><i>num</i></code></dt>
    <dd>Specify the build configuration as an id.</dd>
  </dl>

  <h1>COMMON OPTIONS</h1>

  <p>The common options are summarized below with a more detailed description
  available in <a
  href="bdep-common-options.xhtml"><code><b>bdep-common-options(1)</b></code></a>.</p>

  <dl class="options">
    <dt><code><b>-v</b></code></dt>
    <dd>Print essential underlying commands being executed.</dd>

    <dt><code><b>-V</b></code></dt>
    <dd>Print all underlying commands being executed.</dd>

    <dt><code><b>--quiet</b></code>|<code><b>-q</b></code></dt>
    <dd>Run quietly, only printing error messages.</dd>

    <dt><code><b>--verbose</b></code> <code><i>level</i></code></dt>
    <dd>Set the diagnostics verbosity to <code><i>level</i></code> between 0
    and 6.</dd>

    <dt><code><b>--stdout-format</b></code> <code><i>format</i></code></dt>
    <dd>Representation format to use for printing to
    <code><b>stdout</b></code>.</dd>

    <dt><code><b>--jobs</b></code>|<code><b>-j</b></code> <code><i>num</i></code></dt>
    <dd>Number of jobs to perform in parallel.</dd>

    <dt><code><b>--progress</b></code></dt>
    <dd>Display progress indicators for long-lasting operations, such as
    network transfers, building, etc.</dd>

    <dt><code><b>--no-progress</b></code></dt>
    <dd>Suppress progress indicators for long-lasting operations, such as
    network transfers, building, etc.</dd>

    <dt><code><b>--diag-color</b></code></dt>
    <dd>Use color in diagnostics.</dd>

    <dt><code><b>--no-diag-color</b></code></dt>
    <dd>Don't use color in diagnostics.</dd>

    <dt><code><b>--bpkg</b></code> <code><i>path</i></code></dt>
    <dd>The package manager program to be used for build configuration
    management.</dd>

    <dt><code><b>--bpkg-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the package manager program.</dd>

    <dt><code><b>--build</b></code> <code><i>path</i></code></dt>
    <dd>The build program to be used to build packages.</dd>

    <dt><code><b>--build-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the build program.</dd>

    <dt><code><b>--curl</b></code> <code><i>path</i></code></dt>
    <dd>The curl program to be used for network operations.</dd>

    <dt><code><b>--curl-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the curl program.</dd>

    <dt><code><b>--pager</b></code> <code><i>path</i></code></dt>
    <dd>The pager program to be used to show long text.</dd>

    <dt><code><b>--pager-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the pager program.</dd>

    <dt><code><b>--options-file</b></code> <code><i>file</i></code></dt>
    <dd>Read additional options from <code><i>file</i></code>.</dd>

    <dt><code><b>--default-options</b></code> <code><i>dir</i></code></dt>
    <dd>The directory to load additional default options files from.</dd>

    <dt><code><b>--no-default-options</b></code></dt>
    <dd>Don't load default options files.</dd>
  </dl>

  <h1>DEFAULT OPTIONS FILES</h1>

  <p>See <a
  href="bdep-default-options-files.xhtml"><code><b>bdep-default-options-files(1)</b></code></a>
  for an overview of the default options files. For the <code><b>ci</b></code>
  command the search start directory is the project directory. The following
  options files are searched for in each directory and, if found, loaded in
  the order listed:</p>

  <pre>bdep.options
bdep-ci.options</pre>

  <p>The following <code><b>ci</b></code> command options cannot be specified
  in the default options files:</p>

  <pre>--directory|-d</pre>

  <h1>BUGS</h1>

  <p>Send bug reports to the
  <a href="mailto:users@build2.org">users@build2.org</a> mailing list.</p>

</div>

<div id="footer">
Copyright &#169; 2014-2024 the build2 authors.<br/>
Permission is granted to copy, distribute and/or modify this document under
the terms of the MIT License.
</div>

</body>
</html>
